9.17.2 Filtering Incoming Mail

To use the Spam package to filter incoming mail, you must first set up fancy mail splitting. See Fancy Mail Splitting. The Spam package defines a special splitting function that you can add to your fancy split variable (either nnmail-split-fancy or nnimap-split-fancy, depending on your mail back end):

(: spam-split)

The spam-split function scans incoming mail according to your chosen spam back end(s), and sends messages identified as spam to a spam group. By default, the spam group is a group named ‘spam’, but you can change this by customizing spam-split-group. Make sure the contents of spam-split-group are an unqualified group name. For instance, in an nnimap server ‘your-server’, the value ‘spam’ means ‘nnimap+your-server:spam’. The value ‘nnimap+server:spam’ is therefore wrong—it gives the group ‘nnimap+your-server:nnimap+server:spam’.

spam-split does not modify the contents of messages in any way.

Note for IMAP users: if you use the spam-check-bogofilter, spam-check-ifile, and spam-check-stat spam back ends, you should also set the variable nnimap-split-download-body to t. These spam back ends are most useful when they can “scan” the full message body. By default, the nnimap back end only retrieves the message headers; nnimap-split-download-body tells it to retrieve the message bodies as well. We don’t set this by default because it will slow IMAP down, and that is not an appropriate decision to make on behalf of the user. See Client-Side IMAP Splitting.

You have to specify one or more spam back ends for spam-split to use, by setting the spam-use-* variables. See Spam Back Ends. Normally, spam-split simply uses all the spam back ends you enabled in this way. However, you can tell spam-split to use only some of them. Why this is useful? Suppose you are using the spam-use-regex-headers and spam-use-blackholes spam back ends, and the following split rule:

 nnimap-split-fancy '(|
                      (any "ding" "ding")
                      (: spam-split)
                      ;; default mailbox
                      "mail")

The problem is that you want all ding messages to make it to the ding folder. But that will let obvious spam (for example, spam detected by SpamAssassin, and spam-use-regex-headers) through, when it’s sent to the ding list. On the other hand, some messages to the ding list are from a mail server in the blackhole list, so the invocation of spam-split can’t be before the ding rule.

The solution is to let SpamAssassin headers supersede ding rules, and perform the other spam-split rules (including a second invocation of the regex-headers check) after the ding rule. This is done by passing a parameter to spam-split:

nnimap-split-fancy
      '(|
        ;; spam detected by spam-use-regex-headers goes to ‘regex-spam’
        (: spam-split "regex-spam" 'spam-use-regex-headers)
        (any "ding" "ding")
        ;; all other spam detected by spam-split goes to spam-split-group
        (: spam-split)
        ;; default mailbox
        "mail")

This lets you invoke specific spam-split checks depending on your particular needs, and target the results of those checks to a particular spam group. You don’t have to throw all mail into all the spam tests. Another reason why this is nice is that messages to mailing lists you have rules for don’t have to have resource-intensive blackhole checks performed on them. You could also specify different spam checks for your nnmail split vs. your nnimap split. Go crazy.

You should set the spam-use-* variables for whatever spam back ends you intend to use. The reason is that when loading spam.el, some conditional loading is done depending on what spam-use-xyz variables you have set. See Spam Back Ends.